build(api): check the public API against the last npm release instead of a committed report - #576

Update (2026-09-27): final review

A pre-release review of this PR found two real gaps in scripts/api.ts, both fixed in fix(api): check every subpath entry point and run npm without a shell.

• Five subpaths were left out of the check. readSubpaths dropped every declaration file another one imports from, taking it for a shared chunk. Five real entry points are imported that way (format-cnpj by parse-cnpj's declarations, plus get-certidao-info, is-business-day, is-valid-phone and get-format-license-plate). So a build that stopped shipping one of them passed. An entry point is now a name the build ships as all four of .js, .cjs, .d.ts and .d.cts; a chunk never is, since each format hashes its chunk names on its own. On 2.4.0 that gives 138 subpaths, the five included, and 731 type assertions instead of 717.
• Windows.
  • run() used a shell for every command, which joins the arguments unquoted. A node path under C:\Program Files or a temp directory under a user name with a space broke the tsc step. npm now runs through npm_execpath on the same Node, with no shell. Outside npm run, on Windows, it goes through the shell with every argument quoted.
  • moduleSpecifier wrote ./D:/... when the temp directory and the checkout sit on different drives (C: and D: on the GitHub Windows runners). It now writes the absolute path.
• llms.txt step. The Check workflow's llms.txt step ran git diff on files that are gitignored, so it could never fail. It now only runs the generator. CONTRIBUTING and .bestpractices.json say what that catches: a missing docs file.

Earlier (2026-09-26): the stack was rebuilt from #563 up after #561 dropped three helpers, and scripts/api.ts spells out its directory names.

Every branch of the stack was re-validated: npm run check, the full suite with 100% coverage, knip, jscpd (0 clones), check:api and commitlint.

Stacked on #568. This PR sits on top of #568 (isValidCid10, formatCid10, parseCid10, getCid10) and merges after it, which in turn sits on #564, #566, #569, #565, #567, #573, #561, #563, #562, #560, #559 and #558. Its base branch is claude/cid10, so the diff shown here is the public API check change alone.

What

This PR:

• removes the committed API Extractor baseline (reports/api/brazilian-utils.api.md) and npm run check:api:update;
• makes npm run check:api build the package and run scripts/api.ts.

The script keeps every guarantee the old check gave. The one rule it swaps is "differs from the committed report", replaced by a check against the last release on npm, which is the contract consumers actually depend on.

Design

scripts/api.ts works in a mkdtemp directory under the OS temp dir, outside the repository, and deletes it at the end.

1. API Extractor (guarantees 1 to 3, unchanged). Missing exports (ae-forgotten-export), undocumented declarations (ae-undocumented) and compiler errors in dist/brazilian-utils.d.ts fail as before. api-extractor.json points its default report folder at node_modules/.cache/api-extractor/, so nothing writes into the tree.

2. Breaking-change check (replaces guarantee 4; this step fails the job). The script:

   • runs npm view …@latest, then npm pack, and extracts the tarball;
   • has API Extractor produce the published report;
   • generates a check.ts that the repository's tsc (strict) type-checks.

   The rules:

   • Exports: every export of the release, value or type, must still exist, at the root and in every subpath entry point, and each subpath's .js/.cjs/.d.ts/.d.cts must still be built.
   • Values: const _x: typeof Old.x = New.x.
   • Returns: Returns<Old.f> must be assignable to Returns<New.f>.
   • Types:
     • they are classified by role as input or output;
     • every type must satisfy Old.T assignable to New.T;
     • output types must also satisfy the reverse.
   • Majors: when package.json is on a higher major than the release, breaking changes are listed but do not fail.
   • No registry access: exits with code 2.
   • Never published: skips the comparison.

3. API diff for reviewers (never fails). It lists the added, removed and changed declarations from the two API Extractor reports. The diff goes to stdout and to the Check job summary.

Limits (also in CONTRIBUTING):

• The check proves that code which compiled still compiles, not that it behaves the same.
• It assumes strict consumers.
• A type used only inside a callback parameter is classified by where it is written.
• Generic types appear only in the diff.

Files

• scripts/api.ts (new).
• package.json: check:api runs the script, and check:api:update is removed.
• api-extractor.json: the default report folder moves out of the tree.
• reports/api/brazilian-utils.api.md is deleted, and .gitignore ignores reports.
• The vite.config.ts fmt comment.
• CONTRIBUTING.md: the scripts table, the Public API validation, Breaking changes and Code review sections, and the llms.txt lines.
• .bestpractices.json.
• The .github/workflows/check.yml llms.txt step.
• The docs: commit updates the feature line in README.md and both getting-started.md files.

Verification

Throwaway edits, each applied and then reverted. For every one, npm run check:api behaved as expected:

• These exit 1:
  • removing a JSDoc;
  • un-exporting a used type;
  • removing or renaming a root export;
  • making an option required;
  • narrowing or widening a return type;
  • adding a required property to a returned type;
  • no longer building a subpath (now including the five that were skipped).
• These exit 0 and are listed in the diff:
  • a new export;
  • a new optional parameter;
  • a widened input type.
• A removal with package.json at 3.0.0 is listed and accepted.
• No registry access exits 2.
• A package that was never published exits 0 and skips the comparison.

Open points

• Intentional breaking changes on main. release-please only moves package.json to the next major in its release PR. So a pull request that breaks the API on purpose stays red on this check and has to be merged deliberately. CONTRIBUTING says so.
• Adding a required property to a returned type now fails. New result properties have to be optional.
• The check needs the npm registry, as npm ci already does.

🤖 Generated with Claude Code

https://claude.ai/code/session_01RLkm9YrtAifc6XCLFVEsdH